The Inspector is an OpenDoc™ part that lets you inspect properties of other parts. At this stage it is more an experiment and not a polished utility. Yet part developers may still find it useful. Hopefully in future some of the techniques used by inspector will be used by other OpenDoc utilities and debuggers.
While most OpenDoc parts are concerned with its own data, the Inspector looks around into the data of other parts. The default is to look at the current active part and report on the address and reference count of the parts, frames, facets, transforms etc. The address is enclosed by <> and the reference count by []. The inspector actually acquires some objects it is monitoring and hence these reference counts are increased. When that happens the reference count is enclosed by {}.
When the Inspector becomes the active part, it will not monitor itself because this would not be very interesting, so it will keep monitoring the previously active part. At this point, use the Inspector menu to query more information about the part being monitored.
The query result will appear in the frame for the inspector part . If the data displayed is larger than the frame size, you need to make the part larger. This may take up too much space in your document, so you may want to keep the part small and open a window for it. With some containers you may even be able to delete the part and yet keep the inspector window so it would not take up any room in your document. You can send the results to a log file so that you can view them later. After you turn on logging from the menu, the result of a query will be appended to the file ‘Inspector log file’. You can turn it on and off any time so that you only store the information you want.
OpenDoc properties and value types are supposed to use names under the guideline of ISO standard. Therefore you will find a lot of the name starting with '+//ISO 9070/ANSI::113722::US::CI LABS::'. If we display this it would take up a lot of room, and it would be a hassle for you to type it in. So, the part uses the abbreviation '...' to represent the prefix. So the name will appear in a more reasonable form like '...OpenDoc:Type:Boolean'.
There is some global information that is independent of the active part. The draft is such an object. The Inspector menu also lets you read more information about these objects. Another example is the name space. You can ask for all the names in a name space. For example you can type in '...OpenDoc:NameSpace:EditorKinds' to find out all the editors kinds that have been registered.
While you can gather a lot of useful information this way to aid your debugging, you can go much further if you can also actively modify the information. There is a preconception that once you have generated a part, its behavior is fixed and can only change by another compile. Actually OpenDoc is much more dynamic than that and the Inspector lets you change some data on the fly.
One trivial thing that you can change with Inspector is the reference count on the frame and the part. Of course this would usually get you into trouble. This is the nature of the Inspector. It can give you some powerful commands but it is a two edged sword.
A more useful example would be to change some of the properties of the frame. You can change the droppable flag to allow and disallow embedding more parts. You can change the propagate event flag to change the event flow. You can change frame group and frame sequence to test out your parts use of these properties. All these can be done during run time with the help of the Inspector.
A part developer often would like to know the properties and values of the storage unit. The Inspector offers you a peek at them as well. You can use the edit property menu command to look at either the frame or the part storage unit. You can iterate through the properties and values using the next property and next value buttons in the dialog, or you can access them by name using the get value button. You can also change some values and write them out using the set value button. The Set Value button can be used to add new properties and values to the storage unit when you type in a new property or type name. When you add a new value, the dialog may not be displaying the correct data type. For example, you may be looking at an ISO string when you want to add a new Boolean value. Since the Boolean value is represented by a checkbox, you cannot enter the Boolean value when it is created. So it will be done in two steps. When you first press the Set Value button, if the data type is the same as the one being displayed, the value will be changed/added and so you are done. If the data type is different, then the new value is first created with a default value. You can then change the value to and press the Set Value button again. You can also import or export the value you are looking at from or to the clipboard. When you press the Value->Scrap button, the current value is written to the clipboard. The scrap type will be determined by what is in your type name field. If the type name cannot be translated into an scrap type name, then a generic type 'data' is used. You may also intentionally change the type name so that the data would show up in the clipboard in the name you prefer. For example if you want to write out the type '...OpenDoc:Type:Editor' as TEXT you can put '...MacOS:ScrapType:TEXT' in the type name field when you are doing the export. The Scrap->Value button will do the reverse. It would find the scrap type name for the type name and then look for it in the scrap, import it and write it to the storage unit value.
It must be remembered that the storage unit does not necessary reflect the current value of the part. Rather it represents what was externalized last time. Similarly whatever changes you make to the storage unit will not be visible to the part and will likely be written over in the next externalization. So what you see is really the history and not the current state. One way to get around the problem is to use the externalize menu command to externalize the part or frame so that the current state is written out and then it is read it back again.
The frame and the part are not the only storage units available. These storage units are accessible from the menu because they are being monitored. By following the storage unit references from the frame or the part, it is possible to get to other storage units. In fact you can follow the storage unit reference around and look at other parts in the document. This can be useful when there are parts that cannot be monitored the normal way. For example, if a part cannot become active then we cannot inspect it directly under our scheme of monitoring the active part. It can still be reached by following the storage unit reference and then you can examine the properties of that storage unit. However, inspecting the storage unit property and values is not the same as inspecting the part directly. If you want to monitor a part that cannot be activated, you can access the storage unit of the frame first through the storage unit dialog, then press the 'use as target frame' button to start monitoring that part. Once you do that the frame becomes a fixed target that will not change even as other parts are activated. There is a menu option that allows you to toggle between monitoring the active part and monitoring a fixed part so later you can stop monitoring that part if you wish.
Despite all the Inspector's capabilities, there is nothing unusual about the Inspector. It is an ordinary part written with help with PartMaker. It has the access to the same OpenDoc API as any other part. In fact the Inspector is just a part that puts a thin user interface on top of a very small subset of the OpenDoc API. As an example, we have put a mildly useful function on the Inspector that let you sends a block of text as keyboard input to the part you are monitoring. You may either input the string or read it from a text file. Note that this is not a posting of keystroke to the Macintosh event queue, which would come back to the Inspector itself. Rather this is Inspector talking to the target part directly through the OpenDoc API. While many of us may think of a part as owning an exclusive real estate in the document and the part will be responsible to dealing with user interaction within the confine of this piece of real estate. This little exercise shows that parts can talk to and control each other. As a part developer, you should prepare for such a possibility. Hopefully, this will result in parts that not only work well with the user in the parts’ own islands, but parts can coordinate with each other so a compound document can be greater than the sum of its parts.
Using the same principle, we can add more useful features. You can check to see if a part supports a certain extension. You may also purge a part, which gives you a chance to test out the purge code in you part. You may ask the target part to redraw itself to trigger your imaging code. The execution time will be reported back to you so you can tune you code. A word of caution:when a container part is asked to be redrawn, only the container part is being redrawn, so you may temporarily lose the image of the embedded parts. Execution time will also be reported for part externalization.
The inspector is really an experiment that illustrates a philosophy that can expand the horizon of parts. It is not a polished utility. It still has quite a few bugs in it. It does not try to protect you from shooting at you own foot. So you can delete critical properties, screw up the refcount and so forth. So you have to be careful. One thing that you should avoid is to remove a part when it is being monitored. There is also a problem in the 68K version where saved the Inspector window will not show up when the document is reopened, so you should avoid leaving the Inspector part in its own window when the document is closed.
What is the future of the Inspector? As a utility it is better that its functions be absorbed into debuggers and other professional utilities. We categorize the current Inspector as a thin user interface on top of a limited subset of the OpenDoc API. In future we may change the Inspector to be a testbed to a more complete set of OpenDoc API, where developers may try out the API to learn to use the OpenDoc API. It may be possible to write script to test out ideas before committing them to functions for parts. We can also add more calls to your test parts, along the same line as currently done for draw, purge, keystroke so that Inspector can be used to test out your part.
In conclusion, the Inspectors shows that OpenDoc is a very dynamic system and that no part is an island. Part developers can take advantage of that to write more powerful parts. If in the mean time, the Inspector can help you to debug and test parts, that is an added bonus.
